【CMake 语法】(12) CMake 宏和函数

函数: function, endfunction，支持语法如下：

定义个名为 的函数，该函数接收名为 … 的参数， 表示函数定义的功能，在调用函数之前不会被执行。

一个函数打开一个新的作用域，请参阅 set(var PARENT_SCOPE)。 https://cmake.org/cmake/help/v3.19/command/set.html

有关函数内部策略的行为，请参阅 cmake_policy()。 https://cmake.org/cmake/help/v3.19/command/cmake_policy.html

函数调用的函数名不区分大小写。

案例，定义一个名为 “foo” 的函数，根据不同大小写的函数名调用。

建议函数名全部使用小写。

cmake_language(CALL ...) 既可以调用函数，也可以调用宏。该命令不会引入新的变量或策略范围。

当函数被调用时，首先通过实参替换形参 ${arg1}, …，然后作为普通命令调用。

案例，定义一个对变量求和的函数。

注意：似乎是通过 set(x1 10) 命令将实参值 10 设置到形参变量 x1 中，然后在函数内通过 ${x1} 形式引用参数值。

除了引用形参之外，你还可以引用 ARGC 变量 和 ARGVn 变量 来引用参数，ARGC 表示参数数量，以及 ARGV0, ARGV1, ARGV2, … 将具有传入参数的值。这有助于创建带有可选参数的函数。

案例，定义一个函数，输出参数数量和传入的每个参数值

注意: 用 ARGVn 变量引用实参值，与定义的形参 x1, x2, x3 无关，只与传入的实参有关，就算函数定义是 function(main)，该函数也照样可以使用，或者说这样还更好。

ARGV 变量保存函数的所有参数的列表。

案例，用 ARGV 变量 引用所有参数

此外，ARGN 变量保存超过形参列表之后的参数。如果实参数量大于形参数量，用 ARGN 变量引用预期之外的参数。

案例，用 ARGN 变量引用预期之外的参数

之前案例中形参都为值，那么变量取值的语法 ${VAR} 获取的是值。如果形参为变量的话，那么获取的值为变量，要想获取值的话使用 ${${VAR}}。

案例，如果形参为变量的话，参数引用的就是变量

输出结果

宏: macro, endmacro，支持语法如下：

定义个名为 的宏，该宏接收名为 … 的参数， 表示宏定义的功能，在调用宏之前不会被执行。

有关宏内部策略的行为，请参阅 cmake_policy()。 https://cmake.org/cmake/help/v3.19/command/cmake_policy.html

宏调用名也不区分大小写。

与函数的案例一样，定义一个名为 “foo” 的宏，调用时也可以用 “foo”, “Foo”, “FOO”，也可以使用 cmake_language(CALL ...) 子命令调用宏。

宏也建议，宏名全部使用小写。

调用宏时的参数定义和使用，也与函数一样。

macro() 与 function() 非常相似。尽管如此，还有一些重要的区别。

在函数中，ARGN, ARGC, ARGV and ARGV0, ARGV1, … 是 CMake 意义上的变量。在宏中，它们不是，它们是字符串替换，就像 C 预处理器 对 宏 所做的一样。这会产生许多后果，如下面的 “参数警告” 部分所述。

宏和函数之间的另一个区别是控制流。函数的执行 通过将控制权从调用语句转移到函数体。宏的执行 就像将宏主题粘贴到调用语句的位置一样。这导致宏体中的 return() 不仅终止宏的执行；相反，控制权是从宏调用的范围内返回的。为了避免混淆，建议在宏中完全避免 return()。

案例，在函数仅仅用 return 将控制权返回给函数的调用者

案例，如果函数返回返回值，并不是使用 return，而是通过参数

注意，形参原本的作用域在函数内，只能在函数内使用，但是通过 set(... PARENT_SCOPE) 将变量的作用域设置为当前作用域之外，你可以使用父作用域，也就是作用于函数之外。

注意，如果在函数内部通过 PARENT_SCOPE 设置变量，该变量可以在函数之外使用。

例如，在函数内部设置变量 out_var 的值为 100，在函数外部输出也为 100。

与函数不同，CMAKE_CURRENT_FUNCTION, CMAKE_CURRENT_FUNCTION_LIST_DIR, CMAKE_CURRENT_FUNCTION_LIST_FILE, CMAKE_CURRENT_FUNCTION_LIST_LINE 变量，不是为宏设置的。

宏与函数在调用时，参数处理方面的不同。

由于 ARGN, ARGC, ARGV, ARGV0 等，不是变量，因此你无法使用，诸如以下语句：

在第一种情况下，你可以使用 if(${ARGV1})。 在第二种和第三种情况下，检查是否将可选变量传递给宏的正确方法是使用 if(${ARGC} GREATER 2)。 在最后一种情况下，你可以使用 foreach(loop_var ${ARGN}) 如果需要包含它们，可以使用

注意：如果在调用宏的范围内有一个同名的变量，则使用未引用的名称，将使用现有变量而不是参数。例如：

将遍历 a;b;c，而不是预期那样遍历 x;y;z。原因是，bar 会在 foo 中展开，所以 ARGN 称为 foo 中的变量。

我们一般用 cmake_parse_arguments 命令来解析函数或宏的参数。用 cmake_parse_arguments 命令，可以解析复杂的参数形式。

cmake_parse_arguments 有两种形式，语法如下：

我们以 cmake_parse_arguments 的第一种形式为例。

在设计时，有三种参数， 第一种参数是 表示可选关键词列表，如果传入参数包含此变量名，则为 TRUE，反之为 FALSE。 第二种参数是 表示单值关键词列表，每个关键词仅对应一个值。 第三种参数是 表示多值关键词列表，每个关键词可对应多个值。

要解析的参数 ...，我们一般传入为 ${ARGN} 即可，一般定义的函数或宏是无参的，除非第一个参数不是关键词，那么有多少非关键词变量，定义多少形参。

我们将参数 ${ARGN} 根据 , , 规则进行解析，解析出来的新变量名根据 前缀，按照 prefix_参数名 的形式。

可选参数，我们用 if 语句来实现。

要实现的命令形式，如下：

我们知道 TARGETS 为多值关键词，LIBRARY,RUNTIME,OBJECTS 为可选关键词，CONFIGURATIONS,DESTINATION,COMPONENT,RENAME 为单值关键词，OPTIONAL 为可选关键词。

代码如下：

my_install() 被调用:

在 cmake_parse_arguments 调用之后，将设置以下变量

TARGETS 为多值关键词，传入值为 foo;bar。 LIBRARY,RUNTIME,OBJECTS 为可选关键词，因为仅传入 LIBRARY，LIBRARY 被设置为 TRUE，其他都设置为 FALSE。 CONFIGURATIONS 仅传入关键字，并未传入值，所以值也为空。 COMPONENT,RENAME 为单值关键词，未被传入，所以值为空。 DESTINATION 为单值关键词，传入值为 bin。 OPTIONAL 为可选关键词，被设置为 TRUE。

有两种特殊的变量， 第一个 _UNPARSED_ARGUMENTS 表示未解析的参数，表示传入的参数并不符合 cmake_parse_arguments 命令解析规则，所以有 blub。 第二个 _KEYWORDS_MISSING_VALUES 表示关键字缺失值的参数，表示单值关键词或多值关键词，仅传入关键字，并未传入值，所以有 CONFIGURATIONS。

实现 [LIBRARY|RUNTIME|OBJECTS]，可选值，或者三个选一个。

调用形式

实现 [CONFIGURATIONS [Debug|Release|MinSizeRel|RelWithDebInfo]] 参数为多值关键词，但是值为某些固定选项。

调用形式

调用形式

cmake_parse_arguments 的第二种形式，语法如下：

PARSE_ARGV 仅用于函数。在这种情况下，解析的参数来自调用函数的 ARGVn。解析从第 个参数开始。

定义一个类似 add_executable 命令，要实现的命令形式，如下：

代码如下：

调用形式

在 cmake_parse_arguments 调用之后，将设置以下变量

注意，函数第一个参数，可以通过 形参获取 或者通过 ARGV0 引用。最后的不定参数，可以通过特殊变量 MY_UNPARSED_ARGUMENTS 获取，并通过 foreach 语句 解析。

我们可以在函数定义中，使用特殊变量，用于查看函数执行的情况。CMAKE_CURRENT_FUNCTION 表示函数名，CMAKE_CURRENT_FUNCTION_LIST_DIR 表示函数所在 CMakeLists.txt 文件目录，CMAKE_CURRENT_FUNCTION_LIST_FILE 表示函数所在 CMakeLists.txt 文件路径CMAKE_CURRENT_FUNCTION_LIST_LINE 表示函数执行所在行数。

Project/src/CMakeLists.txt

Project/src/bar/CMakeLists.txt

输出结果为